home *** CD-ROM | disk | FTP | other *** search
/ Personal Computer World 2009 February / PCWFEB09.iso / Software / Linux / SLAX 6.0.8 / slax-6.0.8.iso / slax / base / 006-devel.lzm / usr / include / libkcal / alarm.h next >
Encoding:
C/C++ Source or Header  |  2007-01-15  |  11.5 KB  |  371 lines
  1. /*
  2.     This file is part of libkcal.
  3.  
  4.     Copyright (c) 2001-2003 Cornelius Schumacher <schumacher@kde.org>
  5.  
  6.     This library is free software; you can redistribute it and/or
  7.     modify it under the terms of the GNU Library General Public
  8.     License as published by the Free Software Foundation; either
  9.     version 2 of the License, or (at your option) any later version.
  10.  
  11.     This library is distributed in the hope that it will be useful,
  12.     but WITHOUT ANY WARRANTY; without even the implied warranty of
  13.     MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  14.     Library General Public License for more details.
  15.  
  16.     You should have received a copy of the GNU Library General Public License
  17.     along with this library; see the file COPYING.LIB.  If not, write to
  18.     the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor,
  19.     Boston, MA 02110-1301, USA.
  20. */
  21.  
  22. #ifndef KCAL_ALARM_H
  23. #define KCAL_ALARM_H
  24.  
  25. #include <qstring.h>
  26. #include <qstringlist.h>
  27. #include <qvaluelist.h>
  28.  
  29. #include "customproperties.h"
  30. #include "duration.h"
  31. #include "person.h"
  32. #include "listbase.h"
  33. #include "libkcal_export.h"
  34.  
  35. #include <kdepimmacros.h>
  36.  
  37. namespace KCal {
  38.  
  39. class Incidence;
  40.  
  41. /**
  42.   This class represents an alarm notification.
  43. */
  44. class LIBKCAL_EXPORT Alarm : public CustomProperties
  45. {
  46.   public:
  47.     enum Type { Invalid, Display, Procedure, Email, Audio };
  48.  
  49.     typedef ListBase<Alarm> List;
  50.  
  51.     /**
  52.       Construct a new alarm with variables initialized to "sane" values.
  53.     */
  54.     explicit Alarm( Incidence *parent );
  55.     /**
  56.       Destruct Alarm object.
  57.     */
  58.     ~Alarm();
  59.  
  60.     /**
  61.       Compare this alarm with another one.
  62.     */
  63.     bool operator==( const Alarm & ) const;
  64.     bool operator!=( const Alarm &a ) const { return !operator==( a ); }
  65.  
  66.     /**
  67.       Set the type of the alarm.
  68.       If the specified type is different from the current type of the alarm,
  69.       the alarm's type-specific properties are initialised to null.
  70.       
  71.       @param type type of alarm.
  72.     */
  73.     void setType( Type type );
  74.     /**
  75.       Return the type of the alarm.
  76.     */
  77.     Type type() const;
  78.  
  79.     /**
  80.       Set the alarm to be a display alarm.
  81.       
  82.       @param text text to display when the alarm is triggered.
  83.     */
  84.     void setDisplayAlarm( const QString &text = QString::null );
  85.     /**
  86.       Set the text to be displayed when the alarm is triggered.
  87.       Ignored if the alarm is not a display alarm.
  88.     */
  89.     void setText( const QString &text );
  90.     /**
  91.       Return the text string that displays when the alarm is triggered.
  92.     */
  93.     QString text() const;
  94.  
  95.     /**
  96.       Set the alarm to be an audio alarm.
  97.       
  98.       @param audioFile optional file to play when the alarm is triggered.
  99.     */
  100.     void setAudioAlarm( const QString &audioFile = QString::null );
  101.     /**
  102.       Set the file to play when the audio alarm is triggered.
  103.       Ignored if the alarm is not an audio alarm.
  104.     */
  105.     void setAudioFile( const QString &audioFile );
  106.     /**
  107.       Return the name of the audio file for the alarm.
  108.       
  109.       @return The audio file for the alarm, or QString::null if not an audio alarm.
  110.     */
  111.     QString audioFile() const;
  112.  
  113.     /**
  114.       Set the alarm to be a procedure alarm.
  115.       
  116.       @param programFile program to execute when the alarm is triggered.
  117.       @param arguments arguments to supply to programFile.
  118.     */
  119.     void setProcedureAlarm( const QString &programFile,
  120.                             const QString &arguments = QString::null );
  121.     /**
  122.       Set the program file to execute when the alarm is triggered.
  123.       Ignored if the alarm is not a procedure alarm.
  124.     */
  125.     void setProgramFile( const QString &programFile );
  126.     /**
  127.       Return the name of the program file to execute when the alarm is triggered.
  128.       
  129.       @return the program file name, or QString::null if not a procedure alarm.
  130.     */
  131.     QString programFile() const;
  132.     /**
  133.       Set the arguments to the program to execute when the alarm is triggered.
  134.       Ignored if the alarm is not a procedure alarm.
  135.     */
  136.     void setProgramArguments( const QString &arguments );
  137.     /**
  138.       Return the arguments to the program to run when the alarm is triggered.
  139.       
  140.       @return the program arguments, or QString::null if not a procedure alarm.
  141.     */
  142.     QString programArguments() const;
  143.  
  144.     /**
  145.       Set the alarm to be an email alarm.
  146.       
  147.       @param subject subject line of email.
  148.       @param text body of email.
  149.       @param addressees email addresses of recipient(s).
  150.       @param attachments optional names of files to attach to the email.
  151.     */
  152.     void setEmailAlarm( const QString &subject, const QString &text,
  153.                         const QValueList<Person> &addressees,
  154.                         const QStringList &attachments = QStringList() );
  155.  
  156.     /**
  157.       Send mail to this address when the alarm is triggered.
  158.       Ignored if the alarm is not an email alarm.
  159.     */
  160.     void setMailAddress( const Person &mailAlarmAddress );
  161.     /**
  162.       Send mail to these addresses when the alarm is triggered.
  163.       Ignored if the alarm is not an email alarm.
  164.     */
  165.     void setMailAddresses( const QValueList<Person> &mailAlarmAddresses );
  166.     /**
  167.       Add this address to the list of addresses to send mail to when the alarm is triggered.
  168.       Ignored if the alarm is not an email alarm.
  169.     */
  170.     void addMailAddress( const Person &mailAlarmAddress );
  171.     /**
  172.       Return the addresses to send mail to when an alarm goes off.
  173.     */
  174.     QValueList<Person> mailAddresses() const;
  175.  
  176.     /**
  177.       Set the subject line of the mail.
  178.       Ignored if the alarm is not an email alarm.
  179.     */
  180.     void setMailSubject( const QString &mailAlarmSubject );
  181.     /**
  182.       Return the subject line of the mail.
  183.     */
  184.     QString mailSubject() const;
  185.  
  186.     /**
  187.       Attach this filename to the email.
  188.       Ignored if the alarm is not an email alarm.
  189.     */
  190.     void setMailAttachment( const QString &mailAttachFile );
  191.     /**
  192.       Attach these filenames to the email.
  193.       Ignored if the alarm is not an email alarm.
  194.     */
  195.     void setMailAttachments( const QStringList &mailAttachFiles );
  196.     /**
  197.       Add this filename to the list of files to attach to the email.
  198.       Ignored if the alarm is not an email alarm.
  199.     */
  200.     void addMailAttachment( const QString &mailAttachFile );
  201.     /**
  202.       Return the filenames to attach to the email.
  203.     */
  204.     QStringList mailAttachments() const;
  205.  
  206.     /**
  207.       Set the email body text.
  208.       Ignored if the alarm is not an email alarm.
  209.     */
  210.     void setMailText( const QString &text );
  211.     /**
  212.       Return the email body text.
  213.       
  214.       @return the body text, or QString::null if not an email alarm.
  215.     */
  216.     QString mailText() const;
  217.  
  218.     /**
  219.       Set the time to trigger an alarm.
  220.     */
  221.     void setTime( const QDateTime &alarmTime );
  222.     /**
  223.       Return the date/time when an alarm goes off.
  224.     */
  225.     QDateTime time() const;
  226.     /**
  227.       Return the date/time when the last repetition of the alarm goes off.
  228.       If the alarm does not repeat, this is equivalent to calling time().
  229.     */
  230.     QDateTime endTime() const;
  231.     /**
  232.       Return true, if the alarm has an explicit date/time.
  233.     */
  234.     bool hasTime() const;
  235.  
  236.     /**
  237.       Set offset of alarm in time relative to the start of the event.
  238.     */
  239.     void setStartOffset( const Duration & );
  240.     /**
  241.       Return offset of alarm in time relative to the start of the event.
  242.       If the alarm's time is not defined in terms of an offset relative
  243.       to the start of the event, returns zero.
  244.     */
  245.     Duration startOffset() const;
  246.     /**
  247.       Return whether the alarm is defined in terms of an offset relative
  248.       to the start of the event.
  249.     */
  250.     bool hasStartOffset() const;
  251.  
  252.     /**
  253.       Set offset of alarm in time relative to the end of the event.
  254.     */
  255.     void setEndOffset( const Duration & );
  256.     /**
  257.       Return offset of alarm in time relative to the end of the event.
  258.       If the alarm's time is not defined in terms of an offset relative
  259.       to the end of the event, returns zero.
  260.     */
  261.     Duration endOffset() const;
  262.     /**
  263.       Return whether the alarm is defined in terms of an offset relative
  264.       to the end of the event.
  265.     */
  266.     bool hasEndOffset() const;
  267.  
  268.     /**
  269.       Set the interval between snoozes for the alarm.
  270.       
  271.       @param alarmSnoozeTime the time in minutes between snoozes.
  272.     */
  273.     void setSnoozeTime( int alarmSnoozeTime );
  274.  
  275.     /**
  276.       Get how long the alarm snooze interval is.
  277.       
  278.       @return the number of minutes between snoozes.
  279.     */
  280.     int snoozeTime() const;
  281.  
  282.     /**
  283.       Set how many times an alarm is to repeat itself after its initial
  284.       occurrence (w/snoozes).
  285.     */
  286.     void setRepeatCount( int alarmRepeatCount );
  287.     /**
  288.       Get how many times an alarm repeats, after its initial occurrence.
  289.     */
  290.     int repeatCount() const;
  291.     /**
  292.       Get the time of the alarm's initial occurrence or its next repetition,
  293.       after a given time.
  294.       @param preTime the date and time after which to find the next repetition.
  295.       @return the date and time of the next repetition, or an invalid date/time if
  296.       the specified time is at or after the alarm's last repetition.
  297.     */
  298.     QDateTime nextRepetition(const QDateTime& preTime) const;
  299.     /**
  300.       Get the time of the alarm's latest repetition, or its initial occurrence if
  301.       none, before a given time.
  302.       @param afterTime the date and time before which to find the latest repetition.
  303.       @return the date and time of the latest repetition, or an invalid date/time if
  304.       the specified time is at or before the alarm's initial occurrence.
  305.     */
  306.     QDateTime previousRepetition(const QDateTime& afterTime) const;
  307.     /**
  308.       Get how long between the alarm's initial occurrence and its final repetition.
  309.       @return the number of seconds between the initial occurrence and final repetition.
  310.     */
  311.     int duration() const;
  312.  
  313.     /**
  314.       Toggles the value of alarm to be either on or off.
  315.       Set's the alarm time to be x minutes before dtStart time.
  316.     */
  317.     void toggleAlarm();
  318.  
  319.     /**
  320.       Set the alarm enabled status.
  321.     */
  322.     void setEnabled(bool enable);
  323.     /**
  324.       Get the alarm enabled status.
  325.     */
  326.     bool enabled() const;
  327.  
  328.     /**
  329.       Set the alarm's parent incidence.
  330.     */
  331.     void setParent( Incidence * );
  332.     /**
  333.       Get the alarm's parent incidence.
  334.     */
  335.     Incidence *parent() const  { return mParent; }
  336.  
  337.   protected:
  338.     /**
  339.       @copydoc
  340.       CustomProperties::customPropertyUpdated()
  341.     */
  342.     virtual void customPropertyUpdated();
  343.  
  344.   private:
  345.     Incidence *mParent;          // the incidence which this alarm belongs to
  346.     Type mType;                  // type of alarm
  347.     QString mDescription;        // text to display/email body/procedure arguments
  348.     QString mFile;               // procedure program to run/optional audio file to play
  349.     QStringList mMailAttachFiles;      // filenames to attach to email
  350.     QValueList<Person> mMailAddresses; // who to mail for reminder
  351.     QString mMailSubject;        // subject of email
  352.  
  353.     int mAlarmSnoozeTime;        // number of minutes after alarm to
  354.                                  // snooze before ringing again
  355.     int mAlarmRepeatCount;       // number of times for alarm to repeat
  356.                                  // after the initial time
  357.  
  358.     QDateTime mAlarmTime;        // time at which to trigger the alarm
  359.     Duration mOffset;            // time relative to incidence DTSTART to trigger the alarm
  360.     bool mEndOffset;             // if true, mOffset relates to DTEND, not DTSTART
  361.     bool mHasTime;               // use mAlarmTime, not mOffset
  362.     bool mAlarmEnabled;
  363.  
  364.     class Private;
  365.     Private *d;
  366. };
  367.  
  368. }
  369.  
  370. #endif
  371.